

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>2.2. Scanning a User-Selected Image &mdash; ZBar iPhone SDK Documentation</title>
    <link rel="stylesheet" href="_static/style.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/zbar.ico"/>
    <link rel="top" title="ZBar iPhone SDK Documentation" href="index.html" />
    <link rel="up" title="2. Developer’s Guide" href="devguide.html" />
    <link rel="next" title="2.3. Customizing the Interface" href="custom.html" />
    <link rel="prev" title="2.1. Scanning From the Camera Feed" href="camera.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="custom.html" title="2.3. Customizing the Interface"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="camera.html" title="2.1. Scanning From the Camera Feed"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">ZBarSDK 1.0</a> &raquo;</li>
          <li><a href="devguide.html" accesskey="U">2. Developer&#8217;s Guide</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="scanning-a-user-selected-image">
<h1>2.2. Scanning a User-Selected Image<a class="headerlink" href="#scanning-a-user-selected-image" title="Permalink to this headline">¶</a></h1>
<p>Some applications may need the full resolution offered by camera snapshots, or
need to scan an image from the user&#8217;s photo library.  In these cases you use a
<a class="reference internal" href="ZBarReaderController.html#ZBarReaderController" title="ZBarReaderController"><tt class="xref cpp cpp-class docutils literal"><span class="pre">ZBarReaderController</span></tt></a>.  This reader is a <em>subclass</em> of
<tt class="xref cpp cpp-class docutils literal"><span class="pre">UIImagePickerController</span></tt>, and you use it the same way.  See the
documentation for <tt class="xref cpp cpp-class docutils literal"><span class="pre">UIImagePickerController</span></tt> for more detais.</p>
<ol class="arabic">
<li><p class="first">Create the reader.</p>
<p>This is as simple as creating a new <a class="reference internal" href="ZBarReaderController.html#ZBarReaderController" title="ZBarReaderController"><tt class="xref cpp cpp-class docutils literal"><span class="pre">ZBarReaderController</span></tt></a>:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="n">ZBarReaderController</span> <span class="o">*</span><span class="n">reader</span> <span class="o">=</span> <span class="p">[</span><span class="n">ZBarReaderController</span> <span class="n">new</span><span class="p">];</span>
</pre></div>
</div>
</li>
<li><p class="first">Setup a delegate to receive the results.</p>
<p>The delegate should implement the <a class="reference internal" href="ZBarReaderDelegate.html#ZBarReaderDelegate" title="ZBarReaderDelegate"><tt class="xref cpp cpp-class docutils literal"><span class="pre">ZBarReaderDelegate</span></tt></a> protocol,
which inherits from <tt class="xref cpp cpp-class docutils literal"><span class="pre">UIImagePickerControllerDelegate</span></tt>:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="n">reader</span><span class="p">.</span><span class="n">readerDelegate</span> <span class="o">=</span> <span class="n">self</span><span class="p">;</span>
</pre></div>
</div>
</li>
<li><p class="first">Configure the reader.</p>
<p>You will need to set the <tt class="xref cpp cpp-member docutils literal"><span class="pre">sourceType</span></tt>
appropriately.  Aside from the properties of the reader itself, you can
configure the decoder via the <tt class="xref cpp cpp-member docutils literal"><span class="pre">scanner</span></tt>
property:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="k">if</span><span class="p">([</span><span class="n">ZBarReaderController</span> <span class="nl">isSourceTypeAvailable:</span>
                             <span class="n">UIImagePickerControllerSoureTypeCamera</span><span class="p">])</span>
    <span class="n">reader</span><span class="p">.</span><span class="n">sourceType</span> <span class="o">=</span> <span class="n">UIImagePickerControllerSoureTypeCamera</span><span class="p">;</span>
<span class="p">[</span><span class="n">reader</span><span class="p">.</span><span class="n">scanner</span> <span class="nl">setSymbology:</span> <span class="n">ZBAR_I25</span>
                <span class="nl">config:</span> <span class="n">ZBAR_CFG_ENABLE</span>
                <span class="nl">to:</span> <span class="mi">0</span><span class="p">];</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="custom.html"><em>Customizing the Interface</em></a> and <a class="reference internal" href="optimizing.html"><em>Optimizing the Reader</em></a> for more details.</p>
</li>
<li><p class="first">Present the reader to the user.</p>
<p>As the reader is a UIImagePickerController, it must be presented modally:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">self</span> <span class="nl">presentModalViewController:</span> <span class="n">reader</span>
      <span class="nl">animated:</span> <span class="n">YES</span><span class="p">];</span>
</pre></div>
</div>
</li>
<li><p class="first">Process the results.</p>
<p>The controller will call the
<tt class="xref cpp cpp-member docutils literal"><span class="pre">imagePickerController:didFinishPickingMediaWithInfo:</span></tt> method of
your delegate for a successful decode (NB <em>not</em> every time the user takes a
picture or selects an image).  The barcode data can be obtained using the
<a class="reference internal" href="ZBarReaderController.html#ZBarReaderControllerResults" title="ZBarReaderControllerResults"><tt class="xref c c-data docutils literal"><span class="pre">ZBarReaderControllerResults</span></tt></a> key of the info dictionary.  This key
will return &#8220;something enumerable&#8221;; keep in mind that there may be multiple
results.  You may also retrieve the corresponding image with
<tt class="xref c c-data docutils literal"><span class="pre">UIImagePickerControllerOriginalImage</span></tt> as usual:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nl">imagePickerController:</span> <span class="p">(</span><span class="n">UIImagePickerController</span><span class="o">*</span><span class="p">)</span> <span class="n">reader</span>
 <span class="nl">didFinishPickingMediaWithInfo:</span> <span class="p">(</span><span class="n">NSDictionary</span><span class="o">*</span><span class="p">)</span> <span class="n">info</span>
<span class="p">{</span>
    <span class="kt">id</span><span class="o">&lt;</span><span class="n">NSFastEnumeration</span><span class="o">&gt;</span> <span class="n">results</span> <span class="o">=</span>
        <span class="p">[</span><span class="n">info</span> <span class="nl">objectForKey:</span> <span class="n">ZBarReaderControllerResults</span><span class="p">];</span>
    <span class="n">UIImage</span> <span class="o">*</span><span class="n">image</span> <span class="o">=</span>
        <span class="p">[</span><span class="n">info</span> <span class="nl">objectForKey:</span> <span class="n">UIImagePickerControllerOriginalImage</span><span class="p">];</span>
    <span class="p">...</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">reader</span></tt> parameter will be the actual <a class="reference internal" href="ZBarReaderController.html#ZBarReaderController" title="ZBarReaderController"><tt class="xref cpp cpp-class docutils literal"><span class="pre">ZBarReaderController</span></tt></a>
(again, a subclass <tt class="xref cpp cpp-class docutils literal"><span class="pre">UIImagePickerController</span></tt>).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The delegate method should dismiss the reader and return as soon as
possible; any processing of the results should be deferred until later,
otherwise the user will experience unacceptable latency between the
actual scan completion and the visual interface feedback.</p>
</div>
</li>
<li><p class="first">Dismiss the reader.</p>
<p>Once you have the results you should dismiss the reader:</p>
<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">reader</span> <span class="nl">dismissModalViewControllerAnimated:</span> <span class="n">YES</span><span class="p">];</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is very important to dismiss from the <em>reader</em> (not the presenting
controller) to avoid corrupting the interface.</p>
</div>
</li>
</ol>
<div class="section" id="handling-failure">
<h2>2.2.1. Handling Failure<a class="headerlink" href="#handling-failure" title="Permalink to this headline">¶</a></h2>
<p>It is always possible the user selects/takes an image that does not contain
barcodes, or that the image quality is not sufficient for the ZBar library to
scan successfully.</p>
<p>In this case, and if <tt class="xref cpp cpp-member docutils literal"><span class="pre">showsHelpOnFail</span></tt> is
<tt class="docutils literal"><span class="pre">YES</span></tt>, the integrated help controller will automatically be displayed with
reason set to <tt class="docutils literal"><span class="pre">&quot;FAIL&quot;</span></tt>.</p>
<p>Your delegate may also choose to implement the optional
<tt class="docutils literal"><span class="pre">readerControllerDidFailToRead:withRetry:</span></tt> method to explicitly handle
failures.  If the <tt class="docutils literal"><span class="pre">retry</span></tt> parameter is <tt class="docutils literal"><span class="pre">NO</span></tt>, you <em>must</em> dismiss the reader
before returning, otherwise you may continue and allow the user to retry the
operation.  Note that, if it is enabled, the integrated help will be displayed
when this delegate method is invoked.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">2.2. Scanning a User-Selected Image</a><ul>
<li><a class="reference internal" href="#handling-failure">2.2.1. Handling Failure</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="camera.html"
                        title="previous chapter">2.1. Scanning From the Camera Feed</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="custom.html"
                        title="next chapter">2.3. Customizing the Interface</a></p>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="custom.html" title="2.3. Customizing the Interface"
             >next</a></li>
        <li class="right" >
          <a href="camera.html" title="2.1. Scanning From the Camera Feed"
             >previous</a> |</li>
        <li><a href="index.html">ZBarSDK 1.0</a> &raquo;</li>
          <li><a href="devguide.html" >2. Developer&#8217;s Guide</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2010, Jeff Brown et al.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.1.
    </div>
  </body>
</html>